home *** CD-ROM | disk | FTP | other *** search
/ PC World 2000 February / PCWorld_2000-02_cd.bin / Software / Servis / FFE / ANIM.SWG / 0015_DVI Multimedia File Format.pas < prev    next >
Encoding:
Pascal/Delphi Source File  |  1997-05-11  |  62.5 KB  |  1,780 lines
  1. Appendix F
  2. DVI_ Multimedia File Format
  3.  
  4. This appendix describes the DVI_ multimedia file format used 
  5. for motion video and audio objects, and for storing compressed 
  6. and uncompressed still images.    
  7.  
  8. This appendix provides information about:
  9.  
  10. * File structure and version control strategy
  11.  
  12. * File organization, including tables that describe fields, 
  13.   their settings, and detailed comments, as appropriate
  14.  
  15. * Derived values  
  16.  
  17. In addition, because of its compatibility with files produced 
  18. using the ActionMedia_ II software, the old still image format is 
  19. documented in this appendix. 
  20.  
  21. Introduction
  22.  
  23. DVI technology has defined a file format for storing audio/video 
  24. objects.  Applications should use this and other industry 
  25. standard file formats, to increase interoperability with other
  26. applications such as media editing and manipulation tools.  The 
  27. DVI multimedia file format is particularly appropriate for 
  28. motion video objects that use the compression algorithms, and 
  29. media objects that use ActionMedia II board pixel formats.  
  30. Although this appendix references the  routines and concepts 
  31. used with AVK, the file format itself is not restricted for use 
  32. only with AVK.
  33.  
  34. The DVI multimedia file format was designed to  grow into a 
  35. general purpose repository for complex multimedia objects, 
  36. including information that might be added by media object 
  37. editors.  Therefore, it has some reserved fields that are not
  38. needed for playback of existing files. 
  39.  
  40. The AVK specification does not require the use of the DVI 
  41. multimedia file format.  However, AVK only supports the data 
  42. streaming file conventions used in DVI multimedia files.  
  43. Applications can use other data streaming conventions, by 
  44. converting the data before passing it to and from group buffers.  
  45. The AVKIO sample programs in the AVK software release 
  46. provide examples of programs that read and write files in this 
  47. format.
  48.  
  49. General Considerations
  50.  
  51. Each audio or video file contains one or more streams of data.  
  52. The following information applies to streams and stream data.
  53.  
  54. * Each stream typically contains digital data that describes 
  55. a single audio or video stream.  For example, an audio 
  56. stream can contain ADPCM4 encoded data describing a 
  57. waveform audio channel.  Generally, there can be several 
  58. such streams, all of which are intended for simultaneous 
  59. playback.  
  60.  
  61. * To reduce head movement on the storage device, the data
  62. from the various streams must be interleaved.  A frame is 
  63. the unit of interleaving, and is nominally 1/30 of a 
  64. second.  The actual duration of a frame is stored within 
  65. the file header. 
  66.  
  67. The following sections specify and describe recommended field 
  68. values to use under AVK.  Some existing ActionMedia II 
  69. software files might use values different from those 
  70. recommended in this appendix.  
  71.  
  72. The descriptions list fields, specify how these fields should be 
  73. referenced when playing a file, and describe fields that can be
  74. ignored.  To explain how fields should be referenced, the 
  75. following criteria are used:
  76.  
  77. * Some fields are used only to verify that the file conforms 
  78. to a variation of the  file structure that can be played by AVK.  
  79.  
  80. * Some fields are used to access information that must be 
  81. passed to AVK through appropriate API routines.  
  82.  
  83. * Some fields can be safely ignored. 
  84.  
  85. File Structure
  86.  
  87. A file consists of a set of inter-related data structures that 
  88. describe the organization of the data into streams, the nature of 
  89. the data in each stream, and the actual data itself.  The 
  90. following information describes the various fields in these data 
  91. structures, and how to generate and interpret the data they 
  92. contain.   
  93.  
  94. Some of these fields are shown as bytes, words, or longs (U8, 
  95. I16, U16, I32 or U32).  These are standard AVK data types 
  96. defined in AVKCOM.H.  In the context of file interchange it is 
  97. especially important that the precise length of integer fields be
  98. specified unambiguously.  In many cases, this appendix gives 
  99. both the symbolic names that are defined in .H include files 
  100. provided with the AVK product, and the current values 
  101. associated with these symbols.   
  102.  
  103. The data structures also include explicit fields whose primary 
  104. purpose is to force compiler-independent word and long 
  105. alignment, as appropriate.  These fields use little endian byte 
  106. ordering.  If these files are used with other processor hardware, 
  107. the associated software must convert to and from the 
  108. corresponding byte order.   
  109.  
  110. Some of the fields are described as being "offsets".  In this 
  111. context, an offset is a byte count, measured from the beginning 
  112. of the file to the first byte of some data in the file.  While this 
  113. appendix sometimes specifies recommended values for these 
  114. offsets, during playback the actual offset in the file should 
  115. always be used.  Otherwise, there might be difficulty processing 
  116. existing files and future extensions to the file format.  
  117. Generally, software can move the data pointed at by an offset 
  118. elsewhere in the file, simply by changing the offset value.   
  119. As a general rule, an offset of zero means that the associated 
  120. data is not present. 
  121.  
  122.  
  123.  
  124. Version Control Strategy
  125.  
  126. The data structures within this file format use a common 
  127. strategy to allow controlled growth in functionality, without 
  128. breaking previous functionality.  This strategy is implemented 
  129. by the use of three fields at the beginning of each file and the 
  130. beginning of many internal data structures.  These fields are a 
  131. four character ASCII ID, a version number and a size in bytes.  
  132. All three fields are useful, since each deals with a different kind 
  133. of version mismatch, or binding mismatch problem.
  134.  
  135. HdrID Field
  136.  
  137. The HdrID field is used to validate that this structure is the 
  138. expected kind of data structure.  For the HdrID field at the 
  139. beginning of the file, such a validation is essential, since the 
  140. host file system allows end users to move and rename files at 
  141. will.  For the HdrID fields in internal data structures, validation 
  142. of this field merely provides some assurance that the file data 
  143. has not been corrupted. 
  144.  
  145. HdrSize Field
  146.  
  147. The HdrSize field gives the length of the data structure in bytes, 
  148. and is central to the file version control strategy.  The file 
  149. format is modified by adding new fields at the end of a data 
  150. structure.  Software that uses the latest version of the file format 
  151. must properly set all fields when it creates a file.  
  152.  
  153. Fields that are set include those fields that are no longer needed 
  154. by the latest version of file-reading software. Setting fields 
  155. needed by previous versions allows older programs that have 
  156. not been upgraded to the latest file format version to operate 
  157. correctly within the limitations of the older file format version.
  158. In addition, since some data might not have existed when a 
  159. software version was compiled, extensions to the file format 
  160. have been carefully limited in ways that prevent old software 
  161. from misinterpreting data.
  162.  
  163. File-reading software deals with expected values in three ways: 
  164.  
  165. 1. If the HdrSize in the file is the expected value, this data 
  166. structure has the expected format.  In this case, 
  167. application software can safely interpret the fields, as 
  168. described in the  section, "File Organization".   
  169.  
  170. 2. If the HdrSize in the file is less than the expected value, 
  171. then this is an old format file, and is missing some 
  172. expected information. Each file format version contains 
  173. enough information for the level of processing that had 
  174. been supported at the time the file was created. In this 
  175. case, no missing information was essential to processing 
  176. the file(that is, the fields missing from the file contain 
  177. clearly-defined default values that can be used instead of 
  178. the missing values).   
  179.  
  180. For example, the AvLCim.DCFId field was not part of the 
  181. original file format definition.  This field is set by a 
  182. Digital Compression Facility (DCF) to provide 
  183. information on where the video was compressed.  For 
  184. files that do not contain this field, as indicated by 
  185. AvLCim.HdrSize (or AvLCim.HdrVer), the default value 
  186. specifies that the compression site is unknown.    
  187.  
  188. A convenient software technique for dealing with the 
  189. possibility that HdrSize is less than the expected value is 
  190. to initialize a copy of the data structure with default 
  191. values, and then only read in HdrSize bytes as given by 
  192. the actual HdrSize field in the file. 
  193.  
  194. 3. If the HdrSize in the file is greater than the expected 
  195. value, then this file has a format which was extended 
  196. after the code was written.  In this case, there are new 
  197. fields that have been defined, but the application code 
  198. lacks the knowledge to interpret them.   
  199.  
  200. For file-reading, therefore, only use the information  that 
  201. is described in the version of the file format definition 
  202. that existed when the code was written.  When an old 
  203. executable is provided new format files to process, the 
  204. executable might be able to play or process the new 
  205. format files  by ignoring fields that did not exist when the 
  206. old executable was compiled.  
  207.  
  208. To support this processing scenario, applications always 
  209. set all fields with appropriate values.  These fields can be 
  210. used by older versions of the software, but are ignored by 
  211. the latest version of the software.
  212.  
  213. A desirable file format extension might require the 
  214. addition of new fields that might produce files that could 
  215. not be properly played by old executables.  In this case, a 
  216. new type or SubType might be introduced, as discussed 
  217. in the section called, "Type and Subtype Fields".  Use of 
  218. new Types and Subtypes makes the new data invisible to 
  219. the old executable. 
  220.  
  221. Although in some situations data can be transcribed from 
  222. an old file to a new file, even without knowing what data 
  223. is represented in certain fields, it is recommended that 
  224. applications totally ignore data in unknown Type or 
  225. Subtype fields.  Ignoring the data is the only guaranteed 
  226. way to produce software that is compatible with a later 
  227. file format definition. 
  228.  
  229. HdrVersion Field
  230.  
  231. The corresponding HdrVersion field is incremented whenever a 
  232. new software release adds new fields to a file data structure.  
  233. Thus, either the HdrVersion or HdrSize field can be used to 
  234. detect a file being read that does not conform to the current file 
  235. format definition.   
  236.  
  237. Checking the HdrVersion field before using a MAKE utility 
  238. also provides a convenient way to guard against the effects of 
  239. "blind" recompilation.  For example, suppose the file format has 
  240. been extended to include new fields.  Simply running MAKE 
  241. against the new header file can produce a program that 
  242. generates files with the new size data structures and 
  243. corresponding version numbers, but nevertheless is invalid 
  244. because of initialization problems.  
  245.  
  246. The problem is that the newly-defined fields must be properly 
  247. initialized, which is very unlikely to occur with code that was 
  248. written before these fields were defined.  For example, the 
  249. proper way to default the AvLCim.DCFId field is to -1.  
  250. However, there is no method for software that predates this field 
  251. to provide the correct default.
  252.  
  253. Type And SubType Fields
  254.  
  255. The AvLStrm data structure contains two fields AvLStrm.Type 
  256. and AvLStrm.SubType, whose purpose is to describe the kind of 
  257. data that is contained in a stream.  These fields can also be used 
  258. to make future extensions to the file format.  These fields have a 
  259. limited set of defined values.  An unknown AvLStrm.Type or 
  260. AvLStrm.SubType value indicates that the file format has been 
  261. extended to allow the presence of data whose interpretation is 
  262. totally unknown.  Existing software, encountering such a value, 
  263. should ignore the stream's data.   
  264.  
  265. File Organization
  266.  
  267. The file structure organization illustrated in Figure F-1 consists 
  268. of:  standard file header, AvLFile header, stream headers (one per 
  269. stream), substream headers (minimum one per substream), frame 
  270. data, and a frame directory.
  271.  
  272.  
  273. ED NOTE:  Figures are not available in this plain text version of 
  274. the specification.
  275.  
  276.  
  277. Figure F-1    DVI Multimedia File Format Structures
  278.  
  279.  
  280.  
  281. Standard File Header
  282.  
  283. The first two entries in any file consist of a  standard file header 
  284. and an AvLFile data structure.  
  285.  
  286. typedef struct 
  287. {
  288.   U32 FileId;
  289.   I16 HdrSize, HdrVersion;
  290.   U32 AnnOffset;
  291. } StdFileHdr;
  292.  
  293. The fields in the StdFileHdr data structure are:
  294.  
  295. Type    Field Name    Setting/Comments
  296.  
  297. U32    FileId    Must be set to VSTD_HDR_ID, which equals 
  298.         0x56445649 (that is, VDVI) and should be 
  299.         validated.  
  300.  
  301. I16    HdrSize    Should be set to sizeof(StdFileHdr), which is 12.  
  302.         On playback, this field should be used as 
  303.         described in the section, "Version Control 
  304.         Strategy".  
  305.  
  306.         Since files do exist that have this field incorrectly 
  307.         set, it is recommended that files with 
  308.         StdFileHdr.HdrVersion = 1 ignore this field, and 
  309.         respond as if this field is set to 12. 
  310.  
  311. I16    HdrVersion     Must be set to VSTD_HDR_VER, which is 1.
  312.             On playback, this field value should be validated. 
  313. U32    AnnOffset     Can be set to zero when creating a file, and can 
  314.             be ignored on playback.  It can also be set to 
  315.             point to an otherwise unused portion of the file, 
  316.             and unstructured data placed there.  This pointer 
  317.             could be useful for adding copyright notices to 
  318.             the file.
  319.  
  320. AvLFile Header
  321.  
  322. The AvLFile data structure always follows immediately after the 
  323. StdFileHdr.
  324.  
  325. typedef struct 
  326. {
  327.   U32 HdrID;
  328.   I16 HdrSize, HdrVer, StrmGrpCnt, StrmGrpSize;
  329.   U32 StrmGrpOffset;
  330.   I16 StrmGrpVer, StrmSize, StrmVer, StrmCnt;
  331.   U32 StrmOffset, HdrPoolOffset;
  332.   I32 LabelCnt;
  333.   U32 LabelOffset;
  334.   I16 LabelSize, LabelVer;
  335.   U32 VshOffset;
  336.   U16 VshSize;
  337.   I16 FrmVer;
  338.   I32 FrmCnt, FrmSize;
  339.   U32 FirstFrmOffset, EndOfFrmsOffset;
  340.   I16 FrmHdrSize, FrmDirSize;
  341.   U32 FrmDirOffset;
  342.   I16 FrmDirVer, FrmsPerSec;
  343.   U32 Flag;
  344.   U32 FreeBlockOffset;
  345.   U8 Patch[32];
  346. } AvLFile;
  347.  
  348. The AvLFile header is the master directory of data structures 
  349. within the file.  
  350.  
  351. The fields in the AvLFile header data structure are:
  352.  
  353. Type    Field Name    Setting/Comments
  354.  
  355. U32    HdrID        Must be set to AVL_FILE_ID, which is 
  356.             0x41565353 (that is, "AVSS"), and should be 
  357.             validated on playback.
  358.  
  359. I16    HdrSize     Should be set to sizeof(AvLFile), which is 120.  
  360.             This field should be used on playback as 
  361.             described in the section, "Version Control 
  362.             Strategy".
  363.  
  364. I16    HdrVer         Should be set to AVL_FILE_VER, which is 3.  
  365.             On playback, the value in the file must be less 
  366.             than or equal to this value.  
  367.  
  368. I16    StrmGrpCnt    Should be set to zero, and need not be validated 
  369.             on playback.
  370.  
  371. I16    StrmGrpSize    Should be set to sizeof(AvLStrmGrp), which is 
  372.             28, and need not be validated on playback.  The 
  373.             AvLStrmGrp data structure is not described in 
  374.             this appendix.
  375.  
  376. U32    StrmGrpOffset    Should be set to zero, and need not be validated 
  377.             on playback.
  378.  
  379. I16    StrmGrpVer    Must be set to AVL_STRMGRP_VER, which is 3, 
  380.             and need not be validated on playback.
  381.  
  382. I16    StrmSize    Must be set to sizeof(AvLStrm), which is 44.  
  383.             This field should be used on playback as 
  384.             described in the section, "Version Control 
  385.             Strategy" for the HdrSize field. 
  386.  
  387. I16    StrmVer        Should be set to AVL_STRM_VER, which is 3, 
  388.             and should be used on playback as described in 
  389.             the section, "Version Control Strategy" for the 
  390.             HdrVersion field.
  391.  
  392.  
  393.  
  394. Type    Field Name    Setting/Comments
  395.  
  396. I16    StrmCnt    The number of streams in the file.  This value can 
  397.             be used as the StreamCount parameter with 
  398.             AvkGrpBufCreate.  A stream typically consists 
  399.             of a set of bytes that describes a sequence of 
  400.             images or waveform audio samples.  Each 
  401.             stream type is described in a separate section 
  402.             later in this appendix.
  403.  
  404. U32    StrmOffset     The offset of the array of AvLStrm structures.  
  405.             Usually set to sizeof(StdFileHdr) + sizeof(AvLFile) 
  406.             that is, the offset that points immediately after the 
  407.             AvLFile.  
  408.  
  409.             Other offset values could also be used, provided 
  410.             the array of AvLStrm headers is placed in the file 
  411.             so that this offset points to it.  
  412.  
  413. U32    HdrPoolOffset    The offset of a pool of substream headers, 
  414.             described in the section, "Substream Headers".  
  415.             This field should be set to point to this pool when 
  416.             a file is created.  Typically, this pool begins 
  417.             immediately after the array of AvLStrm headers 
  418.             for StrmCnt, so its value could be set to 
  419.             AvLFile.StrmOffset + (AvLFile.StrmCnt * 
  420.                 sizeof(AvLStrm)) 
  421.             This field need not be used during playback, 
  422.             since the first substream header for each stream 
  423.             can be located through AvLStrm.FirstHdrOffset.
  424.  
  425. I32    LabelCnt    Should be set to zero, and need not be validated 
  426.             on playback.
  427.  
  428. U32    LabelOffset    Should be set to zero, and need not be validated  
  429.             on playback.
  430.  
  431. I16    LabelSize    Should be set to sizeof(AvLLabel), which is 20, 
  432.             and need not be validated on playback. 
  433.  
  434. I16    LabelVer    Should be set to AVL_LABEL_VER, which is 3, 
  435.             and need not be validated on playback.
  436.  
  437.  
  438.  
  439. Type    Field Name    Setting/Comments
  440.  
  441. U32    VshOffset    The offset of the video sequence header (VSH) 
  442.             for this file.  If none of the streams in this file 
  443.             require a VSH, this field and AvLFile.VshSize are 
  444.             zero.  The VSH contains data required for the 
  445.             decompression of all PLV video streams in the 
  446.             file.  The VSH data is passed to AVK through the 
  447.             pWorkData parameter of AvkVidStrmFormat.  
  448.  
  449.             When creating new files under AVK with RTV, set 
  450.             this field to zero.
  451.  
  452.             AVK applications can also create files by 
  453.             combining audio/video data from existing or 
  454.             newly created files.  Such file editing is legitimate 
  455.             under AVK, provided that no stream uses more 
  456.             than one compression algorithm.  
  457.  
  458.             However, there are practical difficulties 
  459.             associated with generating a valid VSH.  The 
  460.             data in the VSH depends on the actual images, 
  461.             and might differ from file to file, even if the files 
  462.             were compressed with the same PLV 
  463.             compression algorithm.  Moreover, the file format 
  464.             only allows for a single VSH per file.  Therefore, 
  465.             the merger of one or more video streams into a 
  466.             single file requires:
  467.  
  468.             *    Combining the original VSHs into a 
  469.                 new VSH
  470.             *    Modification of the compressed bitstreams  
  471.  
  472.             While the PLV algorithms contain sufficient 
  473.             information to implement such software, the 
  474.             process is complex.  Alternatively, the DOS 
  475.             media preparation utility called VAvEd can be 
  476.             used to create a properly merged VSH from 
  477.             several input video streams.  See the Media 
  478.             Preparation Utility Reference For DOS for 
  479.             details on VAvEd.
  480.  
  481. U16    VshSize    The length of the VSH stored in the file. It is 
  482.             passed to AVK through the pWorkDataSize 
  483.             parameter of AvkVidStrmFormat.  When 
  484.             creating a file whose only video is an RTV 2.0 or 
  485.             RTV 2.1 stream, this field should be set to zero.  
  486.             If you create a file with a validly formed VSH, 
  487.             then its size should be stored here. 
  488.  
  489.  
  490.  
  491. Type    Field Name    Setting/Comments
  492.  
  493. I16    FrmVer    Should be set to AVL_FRM_VER, which is 3.  On 
  494.             playback, the value in the file must be less than 
  495.             or equal to this value.  
  496.  
  497. I32    FrmCnt    Should be set to the number of AvLFrm headers 
  498.             in the file. Typically, this field is initialized 
  499.             after all the frame data has been written 
  500.             into the file.  On playback, an application 
  501.             can use this field (or 
  502.             AvLFile.EndOfFrmsOffset) to determine when to                     stop delivering data to AvkGrpBufWrite.
  503.  
  504. I32    FrmSize    The size of a frame (frame header plus data for 
  505.             all streams).  This field is set to zero if the frames 
  506.             in a file have variable length, as is typical of 
  507.             motion video and audio files.
  508.  
  509.             If, however, all frames have exactly the same 
  510.             length, this field contains that length.  Such a file 
  511.             could be generated by using an optional 
  512.             parameter with a DOS media preparation utility 
  513.             called VLayout (see the Media Preparation 
  514.             Utility Reference For DOS for details on 
  515.             VLayout).  Stream sizes per frame can vary, but 
  516.             the sum of all stream data per frame must be 
  517.             fixed in order for this field to be non-zero.
  518.  
  519. U32    FirstFrameOffset    The offset to the first frame of interleaved 
  520.             stream data.  The interleaved data consists of a 
  521.             sequence of AvLFrm headers. 
  522.  
  523.             For playback, this interleaved data should get 
  524.             passed to AvkGrpBufWrite, in order to play the 
  525.             file from the beginning.  For capture,
  526.             AvkGrpBufRead is used to extract the frame 
  527.             data from AVK, which is then formatted into 
  528.             AvLFrm headers for storage in the file.  
  529.             When creating a file, the frame data is placed 
  530.             towards the end of the file, and an appropriate 
  531.             offset stored in this field. 
  532.  
  533.             On playback, this offset is used to locate the first 
  534.             frame data.  To start playing the file from some 
  535.             other point, the appropriate first AvLFrm must be 
  536.             located.  This location process can be done 
  537.             either by parsing through the AvLFrm headers, or 
  538.             by using data stored within the optional frame 
  539.             directory. 
  540.  
  541.  
  542.  
  543. Type    Field Name    Setting/Comments
  544.  
  545. U32    EndOfFrmsOffset    Must be set to the offset to the first byte after the 
  546.             frame data.  When creating a file, its value is 
  547.             typically entered after the last byte of frame data 
  548.             has been entered into the file.  On playback, no 
  549.             data located at or after this address should ever 
  550.             be passed to AvkGrpBufWrite.  
  551.  
  552. I16    FrmHdrSize    The size of the frame header used for all frames. 
  553.             This field must be set to the length of the frame 
  554.             header, which is a value computed as 
  555.             sizeof(AvLFrm) + 4 * (AvLFile.StrmCnt - 1)
  556.  
  557.             The "-1" is needed because the AvLFrm data 
  558.             structure, as defined, already accounts for the 
  559.             presence of one stream.  This field does not have 
  560.             to be validated when a file is played back.  A 
  561.             better check could be implemented using the 
  562.             AvLFrm.ChkSum field, described in the section, 
  563.             "Frame Header".
  564.  
  565. I16    FrmDirSize    Must be set to sizeof(AvLFrmDir), which is 4.
  566.  
  567. U32    FrmDirOffset    The offset to the frame directory.  The frame 
  568.             directory provides information that allows random 
  569.             access to an arbitrary frame within the file.  It is 
  570.             recommended that all new files contain a frame 
  571.             directory, since it is very useful for random 
  572.             access.  Some older files will, however, contain a 
  573.             zero for this field, meaning that the frame 
  574.             directory is missing.  
  575.  
  576.             A DOS media preparation utility called VAvCopy 
  577.             can be used to add a frame directory to such 
  578.             files (see the Media Preparation Utility 
  579.             Reference For DOS for details on VAvCopy).  
  580.             Typically, the frame directory is physically placed 
  581.             immediately after the frame data.
  582.  
  583. I16    FrmDirVer    Must be set to AVL_FRMDIR_VER, which is 3.  
  584.             On playback, the value in the file must be less 
  585.             than or equal to this value.  
  586.  
  587.  
  588.  
  589. Type    Field Name    Setting/Comments
  590.  
  591. I16    FrmsPerSec    Must be set to the frame per second rate,
  592.             rounded to the nearest integer written.  By 
  593.             convention, a value of 25 means precisely 25 fps, 
  594.             while any other value is adjusted by the fact that 
  595.             NTSC is 29.97 frames per second, not 30 frames 
  596.             per second.
  597.  
  598.             If a file is based on PAL original material, but 
  599.             intentionally has a frame rate that is not 25 
  600.             frames per second, then a pad stream must be 
  601.             created in order to specify a frame rate that does 
  602.             not have this NTSC adjustment.  The use of this 
  603.             field during playback to help derive 
  604.             FrameRates to pass to AVK is described in the 
  605.             section, "Derived Values".
  606.  
  607. U32    Flag    Should be set to AVL_FILE_INP_UPDATE while 
  608.             a file is being created, and set to zero before the 
  609.             file is closed.  If a file is read when this field is 
  610.             non-zero, the data in the file might be incomplete, 
  611.             and should not be used.
  612.  
  613. U32    FreeBlockOffset    Should be set to zero when creating a file, and 
  614.             need not be validated during file playback.
  615.  
  616. U8    Patch[32]    Should be set to all zeroes when creating a file, 
  617.             and need not be validated during file playback.
  618.  
  619. Stream Header
  620.  
  621. AvLFile.StrmOffset holds the offset to an array of AvLStrm data 
  622. structures, one for each of the AvLFile.StrmCnt streams in the 
  623. file.  The position in the array defines the stream number.  
  624.  
  625. The AvLStrm data structure is: 
  626.  
  627. typedef struct 
  628. {
  629.   U32 HdrID;
  630.   U16 Type, SubType;
  631.   I16 HdrCnt, NextStrmNum, StrmGrpNum, Pad;
  632.   U32 Flag;
  633.   I32 FrmSize;
  634.   U32 FirstHdrOffset;
  635.   U8 StrmName[16];
  636. } AvLStrm;
  637.  
  638. This data structure describes the general nature of the data in a 
  639. single stream, and points to more detailed information the 
  640. substream header. 
  641.  
  642. The fields in the AvLStrm data structure are:
  643.  
  644. Type    Field Name    Setting/Comments
  645.  
  646. U32    HdrID    Must be set to AVL_STRM_ID, which is 
  647.         0x5354524d (that is, "STRM"), and need not be 
  648.         validated on playback.
  649.  
  650. U16    Type    Identifies the type of stream data.  The stream 
  651.         type contains the following values:
  652.  
  653.         Type        Value    Description
  654.         AVL_T_AUD    2    Compressed audio stream
  655.         AVL_T_CIM    3    Compressed image stream
  656.         AVL_T_ULAY    5    Associated per-frame data
  657.         AVL_T_UIM    6    Uncompressed Image 
  658.                     Stream
  659.         AVL_T_PAD    7    Pad Stream
  660.  
  661.         If a stream has some other value for 
  662.         AvLStrm.Type, its data can and should be 
  663.         ignored.  
  664.  
  665.  
  666.  
  667. Type    Field Name    Setting/Comments
  668.  
  669. U16    SubType    These values depend on the value of 
  670.         AvLStrm.Type, and are described in the various 
  671.         sections on substream headers (AvLCim, 
  672.         AvLUlay, AvLUim, and AvLPad).
  673.  
  674. I16    HdrCnt    Specifies the number of substream headers  
  675.         associated with this stream. This field should be 
  676.         set to one.  
  677.  
  678. I16    NextStrmNum    Should be set to AVL_STRMGRP_END, which is 
  679.         -1, and need not be validated on playback.
  680.  
  681. I16    StrmGrpNum    Should be set to zero, and need not be validated 
  682.         on playback. 
  683.  
  684. I16    Pad    Should be set to zero, and need not be validated 
  685.         on playback.
  686.  
  687. U32    Flag    Should be set to 0x4, if the value in 
  688.         AvLStrm.FrmSize is variable.  This field need not 
  689.         be validated on playback. 
  690.  
  691. I32    FrmSize    The maximum amount of data per frame in a 
  692.         stream.  This field does not include the frame 
  693.         header size.  For example, for the X stream, it is 
  694.         the size of the frame, and for the Y stream, it is 
  695.         the size of the largest Y data component for that 
  696.         stream.  
  697.  
  698.         When creating a file, this value could be 
  699.         computed while the frame data is stored into the 
  700.         file, and then updated into the header after all the 
  701.         frame data has been written.  This field is useful 
  702.         in estimating the maximum size of a frame, as 
  703.         described further in the section, "Derived 
  704.         Values". 
  705.  
  706.  
  707.  
  708. Type    Field Name    Setting/Comments
  709.  
  710. U32    FirstHdrOffset    The offset to the stream header for this stream.  
  711.             The data structure at this offset must correspond 
  712.             to the AvLStrm.Type value.  This data structure 
  713.             contains additional information about the stream, 
  714.             and will be described further in the section, 
  715.             "Substream Headers".  
  716.  
  717. U8    StrmName[16]    A null-terminated ASCII string for the stream 
  718.             name.  StrmName is not used by AVK playback, and can 
  719.             be set to all zeroes (which is interpreted as a null 
  720.             string).  It is helpful, however, to set this field 
  721.             for use with the output of a DOS media preparation 
  722.             utility called VAvCheck.  See the Media 
  723.             Preparation Utility Reference For DOS for details 
  724.             on VAvCheck.
  725.  
  726. Substream Headers
  727.  
  728. An AvLStrm data structure contains general information about a 
  729. stream.  Type-dependent information is stored in substream 
  730. headers of the following type: AvLAud, AvLCim, AvLUlay, 
  731. AvLUim and AvLPad. 
  732.  
  733. All the substream headers are located in a pool pointed to by 
  734. AvLFile.HdrPoolOffset.  The pool is located near the beginning 
  735. of the file, to minimize the amount of seeking while the frame 
  736. data is being processed.  This is especially useful for files stored 
  737. on devices like a CD-ROM that have comparatively slow seek 
  738. times.
  739.  
  740. AvLAud:  The Audio Substream Header
  741.  
  742. The AvLAud substream header describes the global 
  743. characteristics of an audio stream.  
  744.  
  745. typedef struct  
  746. {
  747.   U32 HdrID;
  748.   I16 HdrSize, HdrVer;
  749.   U8 OrigFile[80];
  750.   I32 OrigFrm;
  751.   I16 OrigStrm, Pad;
  752.   I32 FrmCnt;
  753.   U32 NextHdrOffset;
  754.   U8 Lib[16], Alg[16];
  755.   I32 Parm1;
  756.   I16 Parm2, Parm3, LeftVol, RightVol;
  757.   I32 LoopOffset, StartFrm;
  758.   U32 Flag;
  759.   I16 Parm4, Pad2;
  760.   I32 DCFId;
  761. } AvLAud;  
  762.  
  763. For an audio stream, AvLStrm.SubType should be set to and 
  764. validated for the value zero. 
  765.  
  766. The fields in the AvLAud data structure are:
  767.  
  768. Type    Field Name    Setting/Comments
  769.  
  770. U32    HdrID        Should be set to AVL_AUD_ID, which is 
  771.             0x41554449 (that is, "AUDI"), and should be 
  772.             validated on playback.  
  773.  
  774. I16    HdrSize        Should be set to sizeof(AvLAud), which is 168.  
  775.             This field should be used on playback as 
  776.             described in the section on version control 
  777.             strategy. 
  778.  
  779. I16    HdrVer        Should be set to AVL_AUD_VER, which is 5.  On 
  780.             playback, the value in the file must be less than 
  781.             or equal to this value.  
  782.  
  783. U8    OrigFile[80]    Should be set to all zeroes, and need not be 
  784.             validated on playback. 
  785.  
  786. I32    OrigFrm        Should be set to zero, and need not be validated. 
  787.  
  788. I16    OrigStrm    Should be set to zero, and need not be validated. 
  789.  
  790. I16    Pad        Should be set to zero, and need not be validated 
  791.             on playback. 
  792.  
  793. I32    FrmCnt        The number of frames.  
  794.  
  795. U32    NextHdrOffset    The offset to the next substream header  for this 
  796.             stream.  This field should be set to 
  797.             AVL_LAST_HDR, which is 0x7ffffff, or zero for 
  798.             the last header.  
  799.  
  800. U8    Lib[16]        Should be set to all zeroes, and need not 
  801.             be validated. 
  802.  
  803. U8    Alg[16]        When creating a file, this field should be set to a 
  804.             null-terminated text string that identifies the audio 
  805.             compression algorithm.  
  806.  
  807.             On playback, this field is used to derive other 
  808.             quantities that are passed to AVK to control 
  809.             playback, as described in the section, "Derived 
  810.             Values". 
  811.  
  812.  
  813.  
  814. Type    Field Name    Setting/Comments
  815.  
  816. I32    Parm1        Should be set to the audio data rate in bits per 
  817.             second.  This value is related to the 
  818.             SamplesPerSecond value used with 
  819.             AvkAudStrmFormat, as described in the 
  820.             section, "Derived Values".  
  821.  
  822. I16    Parm2        The filter cutoff frequency to be used with the 
  823.             audio.  This should be set to zero.
  824.  
  825. I16    Parm3        Should be set to zero.
  826.  
  827. I16    LeftVol        Should be set to 100 on file creation.  These 
  828.     RightVol    fields are intended to enable an editor to modify 
  829.             the volume level associated with an audio 
  830.             stream. 
  831.  
  832.             On playback, these volume level numbers should 
  833.             be treated as a percentage of full volume, and 
  834.             used to form a multiplier with the application-
  835.             specified volume before that volume is passed to 
  836.             AvkAudStrmVolume.  
  837.  
  838.             In a few old files, this value was set to 4096.  If 
  839.             4096 is found in a file, it should be treated as if it 
  840.             were 100. 
  841.  
  842. I32    LoopOffset    Should be set to -1, and need not be validated on 
  843.             playback.  
  844.  
  845. I32    StartFrm    Should be set to zero, and need not be validated 
  846.             on playback. 
  847.  
  848. U32    Flag        Used to signify monophonic or stereo.  This field 
  849.             is zero for mono and AVL_AUD_STEREO, which 
  850.             is 0x00004000, for stereo.  Files might exist in 
  851.             which the 0x00008000 bit is set.  This bit denotes 
  852.             an old format for adpcm4e stereo which cannot 
  853.             be played by AVK. 
  854.  
  855. I16    Parm4        Should be set to the FrameRate used with 
  856.             AvkAudStrmFormat when audio compression 
  857.             was requested.  Typically, this FrameRate is the 
  858.             same for all streams of the file, and so this field 
  859.             can be set to zero.  For playback, the proper way 
  860.             to determine the audio FrameRate is described in 
  861.             the section, "Derived Values". 
  862.  
  863. I16    Pad2        Should be set to zero, and need not be validated 
  864.             on playback. 
  865.  
  866.  
  867.  
  868. Type    Field Name    Setting/Comments
  869.  
  870. I32    DCFId        Should be set to -1, and need not be validated on 
  871.             playback.  This value denotes generation on an 
  872.             end-user platform.  A value of zero means that 
  873.             the Digital Compression Facility (DCF) it was 
  874.             generated on is unknown.  A current list 
  875.             of DCFId's can be obtained from compression 
  876.             services. 
  877.  
  878. AvLCim:  The Compressed Image And Compressed Video Substream Header
  879.  
  880. The AvLCim substream header is used for compressed motion 
  881. video streams and compressed still images. 
  882. The compressed still images are distinguished by the use of:
  883.  
  884. * Specific values of AvLStrm.SubType
  885.  
  886. * Different values of DeCodeAlg  
  887.  
  888. The various SubTypes that can be used are:
  889.  
  890. SubType            Value    Description
  891.  
  892. AVL_ST_Y        1    Y-channel image data 
  893. AVL_ST_U        11    U-channel image data 
  894. AVL_ST_V        12    V-channel image data 
  895. AVL_ST_YVU        13    YVU image data
  896. AVL_ST_YUV_S        14    YUV image data (Industry 
  897. Standard Order)
  898.  
  899. For the PLV algorithms, three streams (Y, V, U) are used to 
  900. convey the information within one "logical" video stream, 
  901. which explains the  stream counting rules in 
  902. AvkVidStrmCreate and AvkAudStrmCreate. 
  903.  
  904. Two SubTypes, AVL_ST_YVU and AVL_ST_YUV_S, are 
  905. used to hold sequences of images, in which the entire image is 
  906. contained in a single stream.  (The suffix "_S" in 
  907. AVL_ST_YUV_S is used only to distinguish the difference 
  908. between two otherwise very similar SubType names.)  These 
  909. SubTypes differ only in respect to the order in which the color 
  910. components are stored.
  911.  
  912. All DVI video images use a YVU order for the color 
  913. components, except for JPEG.   
  914.  
  915. AVK does not support the playing of motion video for arbitrary 
  916. streams of compressed images, but only for a few explicitly 
  917. identified algorithms.  
  918.  
  919. Such images can, however, be displayed by loading them into 
  920. image buffers, using AvkImgDecompress, and using a suitable 
  921. connector. 
  922.  
  923. typedef  struct 
  924. {
  925.   U32 HdrID;
  926.   I16 HdrSize, HdrVer;
  927.   U8 OrigFile[80];
  928.   I32 OrigFrm;
  929.   I16 OrigStrm, Pad;
  930.   I32 FrmCnt;
  931.   U32 NextHdrOffset;
  932.   I16 XPos, YPos, XLen, YLen;
  933.   I16 XCrop, YCrop, DropFrm, DropPhase;
  934.   I32 StillPeriod;
  935.   I16 BufsMin, BufsMax, DeCodeAlg, Pad2;
  936.   I32 DCFId;
  937. } AvLCim;
  938.  
  939. This substream data structure can be used to store several 
  940. different kinds of compressed images.  The fields in the AvLCim 
  941. data structure are:
  942.  
  943. Type    Field Name    Setting/Comments
  944.  
  945. U32    HdrID        Should be set to AVL_CIM_ID, which is 
  946.             0x43494d47 (that is, "CIMG"), and should be 
  947.             validated on playback. 
  948.  
  949. I16    HdrSize        Should be set to sizeof(AvLCim), which is 136.  
  950.             This field should be used on playback as 
  951.             described in the section, "Version Control 
  952.             Strategy".  
  953.  
  954. I16    HdrVer        Should be set to AVL_CIM_VER, which is 4.  On 
  955.             playback, the value in the file must be less than 
  956.             or equal to this value.  
  957.  
  958. U8    OrigFile[80]    Should be set to zero, and need not be validated 
  959.             at playback. 
  960.  
  961.  
  962.  
  963. Type    Field Name    Setting/Comments
  964.  
  965. I32    OrigFrm        Should be set to zero, and need not be validated 
  966.             at playback. 
  967.  
  968. I16    OrigStrm    Should be set to zero, and need not be validated 
  969.             at playback. 
  970.  
  971. I16    Pad        Should be set to zero, and need not be validated 
  972.             at playback. 
  973.  
  974. I32    FrmCnt        The number of frames until the next substream  
  975.             header applies.  This field should be 
  976.             AVL_LAST_HDR, which is 0x7fffffff.  
  977.  
  978. U32    NextHdrOffset    The offset to the next substream header for this 
  979.             stream.  This field should be set to zero.  
  980.  
  981. I16    XPos        Should be set to zero, and need not be validated 
  982.     YPos        on playback. 
  983.  
  984. I16    XLen         Specifies the maximum width and height for the 
  985.     YLen        decompressed images in this file. 
  986.         
  987.             An AVK application should set these 
  988.             fields properly, and validate that these fields will 
  989.             not overflow the limits imposed by the Xres and 
  990.             Yres passed to the AvkVidStrmFormat call.  
  991.             When using AvkImgDecompress, AVK should 
  992.             report an error if the destination image is too 
  993.             small.  
  994.             However, when playing motion video, the 
  995.             microcode might not detect an attempt to 
  996.             decompress an image into a bitmap too small to 
  997.             hold it, causing unpredictable results.
  998.  
  999. I16    XCrop         Should be set to zero, and  need not be validated 
  1000.     YCrop        on playback.
  1001.  
  1002. I16    DropFrm     Should be set to zero, and need not be validated 
  1003.     DropPhase    on playback. 
  1004.  
  1005.  
  1006.  
  1007. Type    Field Name    Setting/Comments
  1008.  
  1009. I32    StillPeriod     Indicates that the video was compressed such 
  1010.             that every Nth frame was intraframe encoded.  
  1011.             For example, if every image of the stream is a still 
  1012.             image this field should be one.  If this value is 
  1013.             three, then frames numbered "0, 3, 6, 9, 12, ..." 
  1014.             are all still images.  If this value is one, then 
  1015.             every image is a still frame. 
  1016.  
  1017.             In addition to these intraframe coded images, the 
  1018.             stream might contain additional intraframe 
  1019.             encoded images.  The default value of 
  1020.             AVL_CIM_RANDOM_STILL, which is -1, 
  1021.             indicates that intraframe image spacing is 
  1022.             unspecified. 
  1023.  
  1024. I16    BufsMin        Should be set to zero.
  1025.     BufsMax    
  1026.  
  1027. I16    DecodeAlg    Should be set to the decompression algorithm.  
  1028.  
  1029.             On playback, the AvLCim.DecodeAlg value 
  1030.             should be passed to AvkVidStrmFormat or 
  1031.             AvkImgDecompress.  
  1032.  
  1033. I16    Pad2        Should be set to zero, and need not be validated 
  1034.             on playback. 
  1035.  
  1036. I32    DCFId        Operates the same as AvlAud.DCFId.  This field 
  1037.             should be set to -1, and need not be validated on 
  1038.             playback. 
  1039.  
  1040. AvLUlay:  The Underlay Substream Header
  1041.  
  1042. Underlay streams hold digital data associated with the same 
  1043. interval of time as the other streams that are present in each 
  1044. frame.  Generally, each SubType can have its own underlay 
  1045. substream header definition.  
  1046.  
  1047. However, for many kinds of underlay data, the following 
  1048. generic underlay substream header can be used.    
  1049.  
  1050. typedef  struct 
  1051. {
  1052.   U32 HdrID;
  1053.   I16 HdrSize, HdrVer;
  1054.   U8 OrigFile[80];
  1055.   I32 OrigFrm;
  1056.   I16 OrigStrm, Pad;
  1057.   I32 FrmCnt;
  1058.   U32 NextHdrOffset;
  1059.   I32 DCFId;
  1060. } AvLUlay;  
  1061.  
  1062. Only one underlay SubType is supported, to be used for holding 
  1063. SMPTE timecodes (see the section, "SMPTE Timecode 
  1064. Underlay Streams" for details).  In addition, a range from zero 
  1065. through 32767 has been reserved for possible registration of 
  1066. specific, to-be-determined, well-defined uses. SubTypes greater 
  1067. than 32767 will not be controlled and can be freely used for 
  1068. application-specific purposes. 
  1069.  
  1070. In a multiple stream file, several underlay streams can exist 
  1071. with the same SubType, each associated with  another 
  1072. interleaved stream.  In this case, by convention, the data in the 
  1073. underlay stream applies to the closest preceding stream of an 
  1074. appropriate type. 
  1075.  
  1076. The fields in the AvLUlay data structure are:
  1077.  
  1078. Type    Field Name    Setting/Comments
  1079.  
  1080. U32    HdrID        Should be set to AVL_ULAY_ID, which is 
  1081.             0x554e4452 (that is, "UNDR"), and need not be 
  1082.             validated on playback. 
  1083.  
  1084. I16    HdrSize        Should be set to sizeof(AvLUlay), which is 108.  
  1085.             This field should be used on playback, as 
  1086.             described in the section, "Version Control 
  1087.             Strategy".
  1088.  
  1089. I16    HdrVer         Should be set to AVL_ULAY_VER, which is 4.
  1090.             On playback, the value in the file must be less 
  1091.             than or equal to this value.  
  1092.  
  1093. U8    OrigFile[80]    Should be set to zero, and need not be validated 
  1094.             at playback. 
  1095.  
  1096. I32    OrigFrm        Should be set to zero, and need not 
  1097.             be validated at playback. 
  1098.  
  1099. I16    OrigStrm    Should be set to zero, and need not be validated 
  1100.             at playback. 
  1101.  
  1102. I16    Pad        Should be set to zero, and need not be validated 
  1103.             at playback.
  1104.  
  1105. I32    FrmCnt        The number of frames until the next substream  
  1106.             header applies.  This field should be 
  1107.             AVL_LAST_HDR, which is 0x7fffffff.  
  1108.  
  1109. U32    NextHdrOffset    The offset to the next substream header  for this 
  1110.             stream.  This field should be set to zero.  
  1111.  
  1112. I32    DCFId        Operates the same as AvlAud.DCFId.  This field 
  1113.             should be set to -1, and need not be validated on 
  1114.             playback.  
  1115.  
  1116. AvLUim:  The Uncompressed Image Substream Header
  1117.  
  1118. The AvLUim data structure is used to hold uncompressed 
  1119. images.   
  1120.  
  1121. typedef  struct 
  1122. {
  1123.   U32 HdrID;
  1124.   I16 HdrSize, HdrVer;
  1125.   U8 OrigFile[80];
  1126.   I32 OrigFrm;
  1127.   I16 OrigStrm, Pad;
  1128.   I32 FrmCnt;
  1129.   U32 NextHdrOffset;
  1130.   I16 XPos, YPos, XLen, YLen, PixBits, Pad2;
  1131.   I32 DCFId;
  1132. } AvLUim;  
  1133.  
  1134. The fields in the AvLUim data structure are:
  1135.  
  1136. Type    Field Name    Setting/Comments
  1137.  
  1138. U32    HdrID        Should be set to AVL_UIM_ID, which is 
  1139.             0x55494d47 (that is, "UIMG"), and need not be 
  1140.             validated on playback.
  1141.  
  1142. I16    HdrSize        Should be set to sizeof(AvLUim), which is 124.  
  1143.             This field should be used on playback, as 
  1144.             described in the section, "Version Control 
  1145.             Strategy". 
  1146.  
  1147. I16    HdrVer        Should be set to AVL_UIM_VER, which is 4.
  1148.             On playback, the value in the file must be less 
  1149.             than or equal to this value.  
  1150.  
  1151. U8    OrigFile    Should be set to zero, and need not be validated 
  1152.             at playback. 
  1153.     
  1154. I32    OrigFrm        Should be set to zero, and need not be validated 
  1155.             at playback. 
  1156.  
  1157.  
  1158.  
  1159. Type    Field Name    Setting/Comments
  1160.  
  1161. I16    OrigStrm    Should be set to zero, and need not be validated 
  1162.             at playback. 
  1163.  
  1164. I16    Pad        Should be set to zero, and need not be validated 
  1165.             at playback. 
  1166.  
  1167. I32    FrmCnt        The number of frames until the next substream  
  1168.             header applies.  This field should be 
  1169.             AVL_LAST_HDR, which is 0x7fffffff.  
  1170.  
  1171. U32    NextHdrOffset    The offset to the next substream header  for this 
  1172.             stream.  This field should be set to zero.  
  1173.  
  1174. I16    XPos         Should be set to zero, and need not be validated 
  1175.     YPos        on playback. 
  1176.  
  1177. I16    XLen         Specifies the maximum width and height for the 
  1178.     YLen        decompressed images in this file. 
  1179.  
  1180. I16    PixBits        Should be set to the average number of bits per 
  1181.             pixel in the image.  Typical values for this field 
  1182.             are 8, 9, 16 and 24.  On playback, 
  1183.             AvLUim.PixBits should be used to determine the 
  1184.             value of BitmapFormat to pass on a call of 
  1185.             AvkImgCreate.   
  1186.  
  1187. I16    Pad2        Should be ignored and set to zero. 
  1188.  
  1189. I32    DCFId        Operates the same as AvLAud.DCFId. This field
  1190.             should be set to -1, and need not be validated on 
  1191.             playback.  
  1192.  
  1193. AvLPad:  The Pad Substream Header
  1194.  
  1195. Pad streams files are generated by a DOS media preparation 
  1196. utility called VLayout.  See the Media Preparation Utility 
  1197. Reference For DOS for details on VLayout.  A pad steam 
  1198. header can tore a frame rate more accurately than can be done 
  1199. by using AvLFile.FrmsPerSec.
  1200.  
  1201. VLayout generates pad data in the various AvLFrm headers, 
  1202. such that the average rate of data consumption precisely 
  1203. matches the standard data rate from a CD-ROM (153,600 bytes 
  1204. per second).  For VLayout, this pad data is set to all zero.  
  1205. On playback, most of the data in pad streams can be ignored on 
  1206. playback.  However, any existing pad streams should be used to 
  1207. derive accurate FrameRates for all streams during playback, as 
  1208. described in the section, "Derived Values".  
  1209.  
  1210. typedef struct 
  1211. {
  1212.   U32 HdrID;
  1213.   I16 HdrSize, HdrVer;
  1214.   U8 OrigFile[80];
  1215.   I16 OrigStrm, Pad;
  1216.   I32 FrmCnt;
  1217.   U32 NextHdrOffset;
  1218.   I32 ImagesPer, Seconds, VidFast, VidVar, VidRev, VidStart;
  1219.   I16 UlayFast, UlayVar, UlayRev, UlayStart;
  1220.   I16 PipeDepth, PipeStart, MinSeek, MinPad;
  1221.   I32 DCFId;
  1222. } AvLPad;  
  1223.  
  1224. The fields of the AvLPad data structure are:
  1225.  
  1226. Type    Field Name    Setting/Comments
  1227.  
  1228. U32    HdrID        Should be set to AVL_PAD_ID, which is 
  1229.             0x50414421 (that is, "PAD!"), and should be 
  1230.             validated on playback. 
  1231.  
  1232. I16    HdrSize        Should be set to sizeof(AvLPad), which is 144.  
  1233.             This field should be used on playback as 
  1234.             described in the section, "Version Control 
  1235.             Strategy". 
  1236.  
  1237.  
  1238.  
  1239. Type    Field Name    Setting/Comments
  1240.  
  1241. I16    HdrVer         Should be set to AVL_PAD_VER, which is  4.
  1242.             On playback, the value in the file must be less 
  1243.             than or equal to this value.  
  1244.  
  1245. U8    OrigFile[80]    Should be set to zero, and need not be validated 
  1246.             at playback. 
  1247.  
  1248. I16    OrigStrm    Should be set to zero, and need not be validated 
  1249.             at playback. 
  1250.  
  1251. I16    Pad        Should be set to zero, and need not be validated 
  1252.             at playback. 
  1253.  
  1254. I32    FrmCnt        The number of frames until the next substream  
  1255.             header applies.  This field should be 
  1256.             AVL_LAST_HDR, which is 0x7fffffff.  
  1257.  
  1258. U32    NextHdrOffset    The offset to the next substream header  for this 
  1259.             stream.  This field should be set to zero.  
  1260.  
  1261. I32    ImagesPer     Two 32-bit integers whose ratio is the 
  1262.             Seconds    frame rate in images per second.  These fields 
  1263.             should be set to zero, and need not be validated 
  1264.             on playback  
  1265.  
  1266.             On playback, these fields are used to derive the 
  1267.             frame rate for all streams in the file, as described 
  1268.             in the section, "Derived Values". 
  1269.  
  1270. I32    VidFast        Should be set to zero, and need not be validated 
  1271.             on playback. 
  1272.  
  1273. I32    VidVar        Should be set to zero, and need not be validated 
  1274.             on playback. 
  1275.  
  1276. I32    VidRev        Should be set to zero, and need not be validated 
  1277.             on playback. 
  1278.  
  1279. I32    VidStart    Should be set to zero, and need not be validated 
  1280.             on playback. 
  1281.  
  1282. I16    UlayFast    Should be set to zero, and need not be validated 
  1283.             on playback. 
  1284.  
  1285. I16    UlayVar        Should be set to zero, and need not be validated 
  1286.             on playback. 
  1287.  
  1288. I16    UlayRev        Should be set to zero, and need not be validated 
  1289.             on playback. 
  1290.  
  1291.  
  1292.  
  1293. Type    Field Name    Setting/Comments
  1294.  
  1295. I16    UlayStart    Should be set to zero, and need not be validated 
  1296.             on playback. 
  1297.  
  1298. I16    PipeDepth    Should be set to zero, and need not be validated 
  1299.             on playback. 
  1300.  
  1301. I16    PipeStart    Should be set to zero, and need not be validated 
  1302.             on playback. 
  1303.  
  1304. I16    MinSeek        Should be set to zero, and need not be validated 
  1305.             on playback. 
  1306.  
  1307. I16    MinPad         Should be set to zero, and need not be validated 
  1308.             on playback. 
  1309.  
  1310. I32    DCFId         Operates the same as AvLAud.DCFId. This field
  1311.             should be set to -1, and need not be validated on 
  1312.             playback.  
  1313.  
  1314. SMPTE Timecode Underlay Streams
  1315.  
  1316. If the SubType of an underlay stream is AVL_ST_TIMECODE 
  1317. (which is 1), the stream contains SMPTE timecode data.  The 
  1318. data in each frame consists of four bytes which are the Binary-
  1319. Coded-Decimal representation of the HH:MM:SS:FF for that 
  1320. frame, as defined by the SMPTE standard for time codes.  
  1321. Generally, several interleaved audio and/or video streams can 
  1322. exist in a file, each with its own timecode data.  The rule for 
  1323. associating a timecode stream with audio or video data is that 
  1324. the timecode stream refers to the immediately preceding audio 
  1325. or video stream. 
  1326.  
  1327. For example, a file compressed by compression services might 
  1328. have the following six stream types:  
  1329.  
  1330. Y, V, U, Timecode, Audio, Timecode.  
  1331.  
  1332. This stream order indicates that there is valid (and possibly equal) 
  1333. timecode information for both the video and audio data.  
  1334. Typically, the data to fill this stream is extracted from a time 
  1335. code reader at the same time as the original video and audio are 
  1336. digitized.
  1337.  
  1338. Frame Data
  1339.  
  1340. Each frame of data in a DVI Multimedia file is preceded by a 
  1341. frame header, identifying the amount of data per stream.
  1342.  
  1343. Frame Header
  1344.  
  1345. This data structure is used to introduce the actual data of the 
  1346. file. All the other headers only describe this data.  The data 
  1347. consists of a sequence of contiguous AvLFrm header/data pairs, 
  1348. one for each frame of the file.  See Appendix C, "Algorithm 
  1349. Characteristics", for details on interpreting data during playback 
  1350. or capture.
  1351.  
  1352. typedef struct 
  1353. {
  1354.   I32 FrmNum, RevOffset, ChkSum;
  1355. //I32 StrmFrmSize[AvLFile.StrmCnt]  This is invalid C syntax. 
  1356.   I32 StrmFrmSize[1];  //Note, This line has valid C syntax, but has wrong 
  1357.                 array size  
  1358. } AvLFrm;  
  1359.  
  1360.  
  1361.  
  1362. The fields of the AvLFrm data structure are:
  1363.  
  1364. Type    Field Name    Setting/Comments
  1365.  
  1366. I32    FrmNum        The sequential frame number in each file, starting 
  1367.             with zero, allowing several files to be opened and 
  1368.             fed in sequence to AVK. 
  1369.  
  1370.             This field is not used by AVK playback, in order 
  1371.             to allow convenient concatenation of the data 
  1372.             from several files.  
  1373.  
  1374.             This field is generated by AVK capture, for use in
  1375.             identifying the precise time that each frame's data 
  1376.             occurred. 
  1377.  
  1378. I32    RevOffset    The file offset to the previous AvLFrm in the 
  1379.             file (measured from the beginning of the file).  For 
  1380.             the first frame of a file, this file offset is zero.  
  1381.  
  1382.             This field must be properly generated on file 
  1383.             creation.  While AvLFrm.RevOffset is typically 
  1384.             ignored on AVK playback, this offset is used by 
  1385.             some DOS media preparation utilities provided 
  1386.             with ActionMedia II software.  
  1387.  
  1388. I32    ChkSum        Provides an efficient check of whether or not a 
  1389.             given block of data begins with a valid AvLFrm.  
  1390.             Its value is formed by exclusive ORing all 
  1391.             AvLFile.FrmHdrSize 32 bit words in the frame 
  1392.             header (excluding this one) with the constant 
  1393.             AVL_FRM_ID, which is 0x46524d48 (that is, 
  1394.             "FRMH").  This field must be computed by the 
  1395.             application before storing the data received by 
  1396.             AvkGrpBufRead into a file.  This field can 
  1397.             be validated by AVK when the data is passed to 
  1398.             AvkGrpBufWrite. 
  1399.  
  1400.  
  1401.  
  1402. Type    Field Name    Setting/Comments
  1403.  
  1404. I32    StrmFrmSize    Consists of one long word for each of the 
  1405.             AvLFile.StrmCnt streams in the file. This field 
  1406.             contains the byte count for the actual data within 
  1407.             each stream of the file.  This frame data 
  1408.             immediately follows the AvLFrm, with no padding 
  1409.             between the frame data for successive streams.   
  1410.  
  1411.             By convention, there are some special 
  1412.             AvLFrm.StrmFrmSize values, that can be used 
  1413.             with audio streams and compressed image 
  1414.             streams.  The size values zero, eight and sixteen 
  1415.             indicate that no data exists for this frame.  These 
  1416.             byte values have slightly different interpretations 
  1417.             by AVK playback, namely missing, silent audio 
  1418.             and transparent video frames, respectively. 
  1419.  
  1420.             The value eight is only used for audio streams, 
  1421.             and denotes one frame time's worth of silence.  
  1422.             The associated eight bytes of actual data, may 
  1423.             be set to zero.  
  1424.             
  1425.             The value sixteen is used only for 
  1426.             compressed image streams, and denotes one 
  1427.             frame time in which the image on the display 
  1428.             does not change.  The associated 16 bytes of 
  1429.             data must be a valid compressed image 
  1430.             bitstream header.  This header is described in the 
  1431.             section, "Compressed Image Bitstream Header". 
  1432.             In this context, the compressed image bitstream 
  1433.             header consists of eight words with the values: 
  1434.             AvLCim.DecodeAlg, 0, 128, 0, 0, 0, 
  1435.             image_height_in_pixels, image_width_in_pixels.
  1436.  
  1437.             A byte count of zero provides physical spacing of 
  1438.             the frame data, but assumes that some other 
  1439.             mechanism will be used to control the temporal 
  1440.             spacing.
  1441.  
  1442.  
  1443.  
  1444. Compressed Image BitStream Header
  1445.  
  1446. For compressed image streams, the actual data for each frame 
  1447. begins with a 16-byte bitstream header.  For PLV sequences, the 
  1448. image data is contained in three separate streams that do not 
  1449. necessarily have the same values for these fields.  This bitstream 
  1450. header must be present for all compressed images.  If the 
  1451. compression is imported from another system, such as a JPEG 
  1452. image, then a suitable bitstream header must be synthesized and 
  1453. pre-pended.  While in theory, a third party JPEG-conformant 
  1454. decompression processor should ignore this header, it is 
  1455. probably a good idea to strip this header before exporting JPEG 
  1456. images.  
  1457.  
  1458. typedef struct 
  1459. {
  1460.   U16 AlgNum;
  1461.   U16 Flags;
  1462.   U32 NumBits;
  1463.   U32 AlgSpec;
  1464.   U16 YSize;
  1465.   U16 XSize;
  1466. } AvLBsh;  
  1467.  
  1468. The fields of the AvLBsh data structure are:
  1469.  
  1470. Type    Field Name    Setting/Comments
  1471.  
  1472. U16    AlgNum        Contains the AlgName (as passed to 
  1473.             AvkVidStrmFormat) used to compress the 
  1474.             image. 
  1475.  
  1476.  
  1477.  
  1478. Type    Field Name    Setting/Comments
  1479.  
  1480. U16    Flags        Contains information that might be used by editor 
  1481.             programs and for random access.  This flag word 
  1482.             contains various bits that might be useful for 
  1483.             making decisions about individual frames.  
  1484.  
  1485.             All bits and bit combinations not explicitly 
  1486.             described in the following questions are reserved 
  1487.             for future use, and should be masked away 
  1488.             before making any of the following decisions. 
  1489.  
  1490.             *    Is this image intraframe encoded (that is, a 
  1491.                 still frame)?
  1492.  
  1493.                 The status of an image intraframe can always 
  1494.                 be determined by examining 0x4.  If this bit is 
  1495.                 set, this image can be decompressed without 
  1496.                 reference to any other image.  The first 
  1497.                 frame of a file should be a still frame.
  1498.  
  1499.             *    Can this image be used as the last image of a 
  1500.                 self-contained edited subsequence?  
  1501.  
  1502.                 For simple compression algorithms, the 
  1503.                 answer to this question is always yes.  
  1504.                 However, in the class of algorithms not 
  1505.                 supported by AVK, the compressed data in 
  1506.                 the bitstream might not be used until a 
  1507.                 subsequent image has also been 
  1508.                 decompressed.  To write code that will also 
  1509.                 work for such compression algorithms, editing 
  1510.                 programs should determine this image use as 
  1511.                 follows:  
  1512.  
  1513.                 - The answer is yes if bit 0x80 is zero.  
  1514.                 - The answer is also yes if bit 0x80 is one 
  1515.                     and bit 0x40 is one.
  1516.  
  1517.             *    Can this image be replaced by a transparent 
  1518.                 image, with no effect on any other images?
  1519.  
  1520.                 If bit 0x80 is zero, bits 0x300 contain a 
  1521.                 two bit count of the number of 
  1522.                 images until the next 
  1523.                 reference frame. That is, if the 0x300 bits 
  1524.                 are 01, this image might be discarded.  If they 
  1525.                 are 10, this image and the next image might 
  1526.                 be discarded  If they are 11, this image and 
  1527.                 the next two images might be discarded.  If 
  1528.                 the 0x300 bits are 00, there is no information 
  1529.                 about the distance to the next intracoded 
  1530.                 image.  In addition, if AvLCim.StillPeriod 
  1531.                 is not AVL_CIM_RANDOM_STILL, 
  1532.                 AvLCim.StillPeriod can be used to predict the 
  1533.                 distance to the next still image.
  1534.             
  1535.                 If bit 0x80 is one, an image can be discarded 
  1536.                 if the 0x700 bits are 000. 
  1537.  
  1538.  
  1539.  
  1540. Type    Field Name    Setting/Comments
  1541.  
  1542. U32    NumBits        Contains the number of bits in the image, 
  1543.             including this header.  For historical reasons, 
  1544.             RTV 1.0 and RTV 1.5 contain a byte count 
  1545.             instead. 
  1546.  
  1547. U32    AlgSpec        Contains information related to the use of the 
  1548.             VSH data with this image.  For compression 
  1549.             algorithms that do not require a VSH for 
  1550.             decompression, this field will be zero.
  1551.  
  1552. U16    YSize         The height and width  (respectively) of the image 
  1553.     XSize        in pixels.  For the subsampled U and V 
  1554.             PLV streams, these fields describe the height and 
  1555.             width of the subsampled chrominance bitmap. 
  1556.  
  1557. Compressed Audio Bitstream Header
  1558.  
  1559. The frame data for an audio bitstream has an internal structure. 
  1560. Knowledge of this structure is useful for conversion between 
  1561. audio bitstream formats, for editing files containing audio.  
  1562.  
  1563. typedef struct 
  1564. {
  1565.   I16 Word1;
  1566.   I16 Word2;
  1567.   I16 Word3;
  1568.   I16 Word4;
  1569. } 
  1570.  
  1571. This header is generated automatically by AVK when it 
  1572. digitizes and compresses.  However, if a file is edited, or a 
  1573. bitstream is converted from another source, the following 
  1574. information is needed to generate a valid frame. 
  1575.  
  1576. The fields of the compressed audio bitstream header data 
  1577. structure are:
  1578.  
  1579. Type    Field Name    Setting/Comments
  1580.  
  1581. I16    Word1        The number of words in this frame, not counting 
  1582.             the four words of this header.  
  1583.  
  1584. I16    Word2, byte1    The audio algorithm, which is encoded as 
  1585.             follows:  
  1586.  
  1587.             adpcm4e-mono    1
  1588.             adpcm4e-stereo    3
  1589.             pcm8-mono    5
  1590.             pcm8-stereo    7
  1591.  
  1592.     Word2, byte2    This field of a four-word header is always 0xFF.  
  1593.             An audio stream that contains some other value 
  1594.             implies that the audio bitstream did not have a 
  1595.             four-byte header.  Some adpcm4e files exist that 
  1596.             do not have this header.  The format of audio 
  1597.             streams that are missing the audio bitstream 
  1598.             header are not described in this appendix. 
  1599.  
  1600.             AVK will automatically detect the absence of the 
  1601.             audio bitstream header, and apply appropriate 
  1602.             defaults in order to play those bitstreams. 
  1603.  
  1604. I16    Word3        This field contains the sample rate in samples per 
  1605.             second. 
  1606.  
  1607. I16    Word4        This field should be set to zero. 
  1608.  
  1609. The remaining audio data in a frame consists of a concatenated 
  1610. sequence of subframes.  A monophonic subframe consists of 
  1611. precisely 32 bytes, while a stereo subframe consists of precisely 
  1612. 64 bytes. Frames contain an integral number of subframes.  
  1613. Ideally, for a given algorithm and sample rate, the number of 
  1614. subframes per frame would be a constant, generated by a simple 
  1615. formula (bits-per-second divided by bits-per-subframe).  
  1616.  
  1617. In practice, this formula yields a non-integral value.  To deal 
  1618. with this non-integral value, "occasionally" a frame will have an 
  1619. extra subframe so that audio bit rate will average to the right 
  1620. value.  When converting audio data from another file format to 
  1621. play under AVK, these extra subframes must be inserted, 
  1622. because AVK uses this average bit rate to maintain lip-synch. 
  1623. An audio stream can be edited by splicing together subframes.  
  1624.  
  1625. After editing:
  1626.  
  1627. * A valid 4-word audio bitstream header must be generated 
  1628. at the beginning of each frame. 
  1629.  
  1630. * The number of subframes per frame must be adjusted so 
  1631. that the average bit rate is correct.  
  1632.  
  1633. * In addition, when splicing adpcm4e subframes, the first 
  1634.  
  1635. 16 bits of data for the first subframe of a "cut" must be 
  1636. zero.  A "cut" is the beginning of a fragment of 
  1637. continuous audio. 
  1638.  
  1639. The data in the subframes depends on the audio algorithm.  The 
  1640. adpcm4e bitstream format inside a subframe is not documented 
  1641. in this appendix, but is available.  The pcm8 bitstream format is 
  1642. very simple.  A mono bitstream consists of a sequence of 8-bit 
  1643. values representing the instantaneous volume level.  For a stereo 
  1644. bitstream, the data consists of a sequence of two-byte values, 
  1645. each of which represents the instantaneous volume to the left 
  1646. and right speakers respectively.   
  1647.  
  1648. Frame Directory
  1649.  
  1650. The frame directory is useful for random access to a file, and 
  1651. consists of one AvLFrmDir header for each AvLFrm header of 
  1652. the file.  This data is typically (but not necessarily) written 
  1653. towards the end of the file, after all the AvLFrm header data has 
  1654. been entered.  
  1655.  
  1656. Since this data structure has a fixed length, and is present for 
  1657. every frame, it is possible to compute the location of a specific 
  1658. AvLFrmDir header in the file, and seek directly to it.  
  1659.  
  1660. typedef struct 
  1661. {
  1662.   U32 FrmOffset;
  1663. } AvLFrmDir;  
  1664.  
  1665. The 31 least significant bits of AvLFrmDir.FrmOffset is the 
  1666. offset to the associated AvLFrm header in the file.   
  1667. The high order bit is 1, if this frame can be used for a random 
  1668. access to the frame data of every stream in the file.  The first 
  1669. frame of a file must be usable for random access.
  1670. This bit can be set by using information about each compressed 
  1671. image, as described in the section,  "Compressed Image 
  1672. Bitstream Header". 
  1673.  
  1674. Theoretically, an audio stream is only suitable for random 
  1675. access if it has the same FrameRate as the video streams with 
  1676. which it is interleaved.  However, in practice, all the audio 
  1677. algorithms supported will quickly resynchronize, even if started 
  1678. in the middle of an audio frame. 
  1679.  
  1680. A frame directory can also be generated through use of an 
  1681. optional parameter to the DOS media preparation utility 
  1682. VAvCopy.  See the Media Preparation Utility Reference For 
  1683. DOS for details on VAvCopy.
  1684.  
  1685. Derived Values
  1686.  
  1687. The preceding sections describe the values explicitly encoded 
  1688. into the current file format.  This section summarizes the rules 
  1689. for deriving the values of several quantities not explicitly 
  1690. present in a file.  
  1691.  
  1692. AVK Frame Rate
  1693.  
  1694. In AVK, the frame rate received is designated as microseconds 
  1695. per frames.  However, since the DVI multimedia file format 
  1696. designates frame rate as frames per second, an application must 
  1697. translate the designation.  
  1698.  
  1699. When audio is combined with video in a file with interleaved 
  1700. streams, each chunk of audio and video data should have the 
  1701. same playing time.  Therefore, explicitly chunking the audio 
  1702. data so that it has the same frame rate as the video allows 
  1703. cutting and pasting of interleaved audio/video data to form 
  1704. edited files.  A DOS media preparation utility such as VAvEd 
  1705. can be used for this cutting and pasting process.  See the Media 
  1706. Preparation Utility Reference For DOS for details on 
  1707. VAvEd.
  1708.  
  1709. For AVK, the frame rate of the file is also used to control the 
  1710. synchronization of audio and video data.  To synchronize its 
  1711. play against a wall clock, each stream processed uses data that 
  1712. is structured into frames with a known playback duration.  
  1713. PAL original material is also fully supported in AVK.  
  1714. Therefore, the following rules apply for determining the frame 
  1715. rate of the streams of an existing file:
  1716.  
  1717. * First, determine if the file has a pad stream.  If a pad 
  1718. stream exists, the pad stream should be used to compute 
  1719. the frame rates of all streams in the file.  
  1720.  
  1721. To determine whether or not a file has a pad stream, 
  1722. examine the AvLStrm data structures, looking for a 
  1723. structure whose AvLStrm.Type is AVL_T_PAD (that is, 
  1724. 7).  
  1725.  
  1726. * In rare cases, a file can contain several pad streams, in 
  1727. which case the last pad stream should be used for frame 
  1728. rate calculations.  Since the AvLStrm header data is 
  1729. stored as an array of fixed length structures, it is straight 
  1730. forward to search all AvLStrm header data in reverse 
  1731. order. 
  1732.  
  1733. * After identifying the pad stream, access 
  1734. AvLPad.ImagesPer and AvLPad.Seconds.  These values 
  1735. can be converted to a frame rate in AVK units 
  1736. (microseconds per frame), using the formula: 
  1737.  
  1738.     FrameRate = Round ((1,000,000 * 
  1739.         AvLPad.Seconds)/AvLPad.ImagesPer))
  1740.  
  1741. * If the file does not contain a pad stream, the frame rate of 
  1742. video steams is found by examining 
  1743. AvLFile.FrmsPerSec.  This value is stored as an integer.  
  1744.  
  1745. To convert it to a frame rate, use the formula: 
  1746.  
  1747.     FrameRate = Round ((1,000,000/AvLFile.FrmsPerSec) * 
  1748.         NTSC_ADJUSTMENT)
  1749.     The symbol NTSC_ADJUSTMENT is 1001/1000 or 1.  
  1750.  
  1751. The value "1" is only used when AvLFile.FrmsPerSec is 
  1752. exactly 25. 
  1753.  
  1754. * If the file does not contain a pad stream, the frame rate 
  1755. for an audio stream can be determined by examining 
  1756. AvLAud.Parm4.  If AvLAud.Parm4 is not present (as 
  1757. indicated by the value in AvLAud.HdrSize or 
  1758. AvLAud.HdrVer), or if its value is zero, the audio frame 
  1759. rate is derived from AvLFile.FrmsPerSec, as described.  
  1760.  
  1761. If AvLAud.Parm4 is nonzero, the audio frame rate is 
  1762. derived by substituting AvLAud.Parm4 for 
  1763. AvLFile.FrmsPerSec in the formula above. 
  1764.  
  1765. When a file is created, all its streams should have the same 
  1766. frame rate.  If this frame rate can be accurately represented via 
  1767. AvLFile.FrmsPerSec, there is no need to include a pad stream. 
  1768. However, if the frame rate cannot be regenerated by the above 
  1769. calculation, the file should be created with a pad stream so that 
  1770. an accurate frame rate can be stored within it. 
  1771.  
  1772. Maximum Frame Size And Group Buffer Size
  1773.  
  1774. When creating a group buffer for AVK, it is important to know 
  1775. the largest size of a frame that might be found in the file.  While 
  1776. this information is not explicitly recorded in a file, a reasonable 
  1777. upper limit can be estimated by using the AvLStrm.FrmSize 
  1778. values in each AvLStrm.  This upper bound is the sum of the 
  1779. AvLStrm.FrmSize fields from every stream of the file, plus the 
  1780. length of a frame header (that